package org.example.exampreparationtreasure.service;

import com.baomidou.mybatisplus.core.metadata.IPage;
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
import org.example.exampreparationtreasure.model.entity.IncorrectQuestionRecord;

/**
 * 错题记录服务接口。
 * <p>
 * 提供错题记录的查询、分页、按分类筛选等功能，支持错题本管理和错题分析。
 * </p>
 */
public interface IncorrectQuestionRecordService {
    
    /**
     * 分页查询指定用户在指定分类下的错题记录。
     * 
     * @param page 分页参数
     * @param userId 用户ID
     * @param categoryId 分类ID
     * @return 分页结果
     */
    IPage<IncorrectQuestionRecord> getIncorrectQuestionsByCategory(
            Page<IncorrectQuestionRecord> page, Long userId, Long categoryId);
    
    /**
     * 分页查询指定用户在指定分类及其所有子分类下的错题记录。
     * 
     * @param page 分页参数
     * @param userId 用户ID
     * @param categoryId 父分类ID（会自动包含其所有子分类）
     * @param includeSubcategories 是否包含子分类，true表示包含所有子分类
     * @return 分页结果
     */
    IPage<IncorrectQuestionRecord> getIncorrectQuestionsByCategoryWithSubcategories(
            Page<IncorrectQuestionRecord> page, Long userId, Long categoryId, boolean includeSubcategories);
    
    /**
     * 分页查询指定用户的所有错题记录。
     * 
     * @param page 分页参数
     * @param userId 用户ID
     * @return 分页结果
     */
    IPage<IncorrectQuestionRecord> getAllIncorrectQuestionsByUser(
            Page<IncorrectQuestionRecord> page, Long userId);
    
    /**
     * 添加错题记录。
     * 
     * @param userId 用户ID
     * @param questionId 题目ID
     * @param mistakeReason 错误原因
     * @return 是否添加成功
     */
    boolean addIncorrectQuestion(Long userId, Long questionId, String mistakeReason);
    
    /**
     * 删除错题记录（表示用户已掌握该题）。
     * 
     * @param userId 用户ID
     * @param questionId 题目ID
     * @return 是否删除成功
     */
    boolean removeIncorrectQuestion(Long userId, Long questionId);
    
    /**
     * 直接分页查询指定用户在指定分类下的错题记录（基于错题记录表的category_id字段）。
     * 
     * @param page 分页参数
     * @param userId 用户ID
     * @param categoryId 分类ID
     * @return 分页结果
     */
    IPage<IncorrectQuestionRecord> getIncorrectQuestionsByCategoryDirect(
            Page<IncorrectQuestionRecord> page, Long userId, Long categoryId);
    
    /**
     * 修复缺失的 category_id 字段数据
     * 
     * @return 修复的记录数量
     */
    int fixMissingCategoryIds();
}
